<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <title>Building replicated applications</title>
    <link rel="stylesheet" href="gettingStarted.css" type="text/css" />
    <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
    <link rel="start" href="index.html" title="Berkeley DB Programmer's Reference Guide" />
    <link rel="up" href="rep.html" title="Chapter 12.  Berkeley DB Replication" />
    <link rel="prev" href="rep_pri.html" title="Replication environment priorities" />
    <link rel="next" href="rep_mgr_meth.html" title="Replication Manager methods" />
  </head>
  <body>
    <div xmlns="" class="navheader">
      <div class="libver">
        <p>Library Version 11.2.5.3</p>
      </div>
      <table width="100%" summary="Navigation header">
        <tr>
          <th colspan="3" align="center">Building replicated applications</th>
        </tr>
        <tr>
          <td width="20%" align="left"><a accesskey="p" href="rep_pri.html">Prev</a> </td>
          <th width="60%" align="center">Chapter 12. 
		Berkeley DB Replication
        </th>
          <td width="20%" align="right"> <a accesskey="n" href="rep_mgr_meth.html">Next</a></td>
        </tr>
      </table>
      <hr />
    </div>
    <div class="sect1" lang="en" xml:lang="en">
      <div class="titlepage">
        <div>
          <div>
            <h2 class="title" style="clear: both"><a id="rep_app"></a>Building replicated applications</h2>
          </div>
        </div>
      </div>
      <p>The simplest way to build a replicated Berkeley DB application is to first
build (and debug!) the transactional version of the same application.
Then, add a thin replication layer: application initialization must be
changed and the application's communication infrastructure must be
added.</p>
      <p>The application initialization changes are relatively simple.
Replication Manager provides a communication infrastructure, but
in order to use the replication Base APIs you must provide your own.</p>
      <p>For implementation reasons, all replicated databases must reside in
the data directories set from <a href="../api_reference/C/envset_data_dir.html" class="olink">DB_ENV-&gt;set_data_dir()</a> (or in the
default environment home directory, if not using
<a href="../api_reference/C/envset_data_dir.html" class="olink">DB_ENV-&gt;set_data_dir()</a>), rather than in a subdirectory below the
specified directory.  Care must be taken in applications using
relative pathnames and changing working directories after opening the
environment.  In such applications the replication initialization code
may not be able to locate the databases, and applications that change
their working directories may need to use absolute pathnames.</p>
      <p>During application initialization, the application performs
three additional tasks: first, it must specify the <a href="../api_reference/C/envopen.html#envopen_DB_INIT_REP" class="olink">DB_INIT_REP</a>
flag when opening its database environment and additionally, a
Replication Manager application must also specify the <a href="../api_reference/C/dbopen.html#open_DB_THREAD" class="olink">DB_THREAD</a> flag;
second, it must provide Berkeley DB information about its communications
infrastructure; and third, it must start the Berkeley DB replication system.
Generally, a replicated application will do normal Berkeley DB recovery and
configuration, exactly like any other transactional application.</p>
      <p>
    Replication Manager applications configure the built-in communications
    infrastructure by calling obtaining a <a href="../api_reference/C/db_site.html" class="olink">DB_SITE</a> handle, and then using
    it to configure the local site. It can optionally obtain one or more
    <a href="../api_reference/C/db_site.html" class="olink">DB_SITE</a> handles to configure remote sites.  Once the environment has
    been opened, the application starts the replication system by calling
    the <a href="../api_reference/C/repmgrstart.html" class="olink">DB_ENV-&gt;repmgr_start()</a> method.
</p>
      <p>A Base API application calls the
<a href="../api_reference/C/reptransport.html" class="olink">DB_ENV-&gt;rep_set_transport()</a> method to configure the entry point to its own
communications infrastructure, and then calls the
<a href="../api_reference/C/repstart.html" class="olink">DB_ENV-&gt;rep_start()</a> method to join or create the replication group.</p>
      <p>When starting the replication system, an application has two choices:
it may choose the group master site explicitly, or alternatively it
may configure all group members as clients and then call for an
election, letting the clients select the master from among
themselves.  Either is correct, and the choice is entirely up to the
application.</p>
      <p>Replication Manager applications make this choice simply by setting 
the flags parameter to the <a href="../api_reference/C/repmgrstart.html" class="olink">DB_ENV-&gt;repmgr_start()</a> method.</p>
      <p>For a Base API application, the result of
calling <a href="../api_reference/C/repstart.html" class="olink">DB_ENV-&gt;rep_start()</a> is usually the discovery of a master, or the
declaration of the local environment as the master.  If a master has
not been discovered after a reasonable amount of time, the application
should call <a href="../api_reference/C/repelect.html" class="olink">DB_ENV-&gt;rep_elect()</a> to call for an election.</p>
      <p>Consider a Base API application with multiple processes or multiple 
environment handles
that modify databases in the replicated environment.  All modifications
must be done on the master environment.  The first process to join or
create the master environment must call both the
<a href="../api_reference/C/reptransport.html" class="olink">DB_ENV-&gt;rep_set_transport()</a> and the <a href="../api_reference/C/repstart.html" class="olink">DB_ENV-&gt;rep_start()</a> method.  Subsequent
replication processes must at least call the <a href="../api_reference/C/reptransport.html" class="olink">DB_ENV-&gt;rep_set_transport()</a> method.
Those processes may call the <a href="../api_reference/C/repstart.html" class="olink">DB_ENV-&gt;rep_start()</a> method (as long as they use the
same master or client argument).  If multiple processes are modifying
the master environment there must be a unified communication
infrastructure such that messages arriving at clients have a single
master ID.  Additionally the application must be structured so that all
incoming messages are able to be processed by a single <a href="../api_reference/C/env.html" class="olink">DB_ENV</a>
handle.</p>
      <p>Note that not all processes running in replicated environments need to
call <a href="../api_reference/C/repmgrstart.html" class="olink">DB_ENV-&gt;repmgr_start()</a>, <a href="../api_reference/C/reptransport.html" class="olink">DB_ENV-&gt;rep_set_transport()</a> or <a href="../api_reference/C/repstart.html" class="olink">DB_ENV-&gt;rep_start()</a>.  Read-only
processes running in a master environment do not need to be configured
for replication in any way.  Processes running in a client environment
are read-only by definition, and so do not need to be configured for
replication either (although, in the case of clients that may become
masters, it is usually simplest to configure for replication on process
startup rather than trying to reconfigure when the client becomes a
master).  Obviously, at least one thread of control on each client must
be configured for replication as messages must be passed between the
master and the client.</p>
      <p>Any site in a replication group may have its own private
transactional databases in the environment as well.  A site may
create a local database by specifying the <a href="../api_reference/C/dbset_flags.html#dbset_flags_DB_TXN_NOT_DURABLE" class="olink">DB_TXN_NOT_DURABLE</a>
flag to the <a href="../api_reference/C/dbset_flags.html" class="olink">DB-&gt;set_flags()</a> method.  The application
must never create a private database with the same name
as a database replicated across the entire environment
as data corruption can result.</p>
      <p>For implementation reasons, Base API applications must process 
all incoming replication messages 
using the same <a href="../api_reference/C/env.html" class="olink">DB_ENV</a> handle.  It is not required that
a single thread of control process all messages, only that all threads
of control processing messages use the same handle.</p>
      <p>No additional calls are required to shut down a database environment
participating in a replication group.  The application should shut down
the environment in the usual manner, by calling the <a href="../api_reference/C/envclose.html" class="olink">DB_ENV-&gt;close()</a> method.
For Replication Manager applications, this also terminates all network
connections and background processing threads.</p>
    </div>
    <div class="navfooter">
      <hr />
      <table width="100%" summary="Navigation footer">
        <tr>
          <td width="40%" align="left"><a accesskey="p" href="rep_pri.html">Prev</a> </td>
          <td width="20%" align="center">
            <a accesskey="u" href="rep.html">Up</a>
          </td>
          <td width="40%" align="right"> <a accesskey="n" href="rep_mgr_meth.html">Next</a></td>
        </tr>
        <tr>
          <td width="40%" align="left" valign="top">Replication environment priorities </td>
          <td width="20%" align="center">
            <a accesskey="h" href="index.html">Home</a>
          </td>
          <td width="40%" align="right" valign="top"> Replication Manager methods</td>
        </tr>
      </table>
    </div>
  </body>
</html>
